QuickTime For Windows Programmers

Movie Controllers

The preferred way to present a movie is with a movie controller. This is a QuickTime component that presents the user with a standard set of controls for running the movie and controlling its direction, speed, and so on. Movie controllers and the functions available for working with them are discussed fully in Inside Macintosh: QuickTime Components and QuickTime 3 Reference.

You create a movie controller with the QuickTime function NewMovieController :



 
MovieController

    NewMovieController

        (Movie        theMovie,             // Movie to be displayed

         const Rect  *movieRect,            // Rectangle to display it in

         long         someFlags)            // Option flags

Parameter theMovie is the movie identifier you received when you read the movie in with NewMovieFromFile (as shown in the section "Movies and Movie Files" ). The second parameter, movieRect , specifies the rectangle in which to display the movie on the screen. The parameter someFlags specifies various options, such as whether to display the movie with a frame around it, how to position it within the specified rectangle, and whether to scale it to fit the rectangle. (If you want it to fit the rectangle exactly, you can get the dimensions of the movie's boundary rectangle with the QuickTime function GetMovieBox .)

Because of its Mac OS origins, a movie controller is driven by events rather than messages. Events are similar in concept to Windows-style messages, though different in detail. As you can see in Listing 9 , the QTML event record closely resembles the Windows message structure (MSG ) and contains essentially the same information. (One difference is that unlike a Windows message, the event doesn't identify a particular window to which it applies; this is because all Macintosh events are addressed globally to the program itself, rather than to an individual window.)

Listing 9 Event record



 
struct EventRecord

    {

        EventKind        what;              // Event type

        UInt32           message;           // Additional parametric information

        UInt32           when;              // Time event occurred

        Point            where;             // Mouse position at time of event

        EventModifiers   modifiers;         // State of keyboard modifier keys

        

    };

The QTML utility function NativeEventToMacEvent converts a Windows message into an equivalent QTML event:



 
int

    NativeEventToMacEvent 

        (void         *winMsg,      // Windows message to be converted

         EventRecord  *macEvent)    // Equivalent Macintosh event

The first parameter points to a Windows MSG structure describing the message received by your window procedure; the second points to a QTML event record for the function to fill in to represent an equivalent event, if any. (A nonzero function result indicates that the conversion took place successfully; if the given message doesn't correspond to a Mac OS-style event, the function simply converts it to a null event and returns a zero result.)

The QuickTime function MCIsPlayerEvent



 
ComponentResult

    MCIsPlayerEvent

        (MovieController     mc,            // Movie controller

         const EventRecord  *e)             // Event to be processed

accepts a movie controller and an event record as parameters, determines whether the event is directed to the controller, and processes it as appropriate. This allows the movie controller to "run itself," handling all mouse and keyboard interactions with the user and displaying its movie on the screen accordingly. Even if the movie controller has no interest in the given event (for instance, if it's a null event), the controller receives some processing time to advance the presentation of the movie itself.

Although the function returns a result of type ComponentResult (equivalent to a long integer) to indicate whether the movie controller has processed the event, you should normally ignore this result and simply pass all messages through both MCIsPlayerEvent and your window procedure's normal message dispatch. Listing 10 shows how to use the NativeEventToMacEvent and MCIsPlayerEvent functions to convert each message you receive to an event, then pass it to the window controller for action.

Listing 10 Displaying a movie



 
MovieController   theController;                    // Movie controller for movie



LRESULT

    CALLBACK WinProc

        (HWND     thisWindow,                       // Handle to window

         UINT     msgType,                          // Message type

         WPARAM   wParam,                           // Message-dependent parameter

         LPARAM   lParam)                           // Message-dependent parameter



    {   

        MSG               winMsg;                   // Windows message structure

        EventRecord       qtmlEvt;                  // Macintosh event record

        DWORD             msgPos;                   // Mouse coordinates of message

        

        

        winMsg.hwnd = thisWindow;                   // Window handle

        

        winMsg.message = msgType;                   // Message type

        winMsg.wParam  = wParam;                    // Word-length parameter

        winMsg.lParam  = lParam;                    // Long-word parameter

        

        winMsg.time = GetMessageTime();             // Get time of message

        

        msgPos  = GetMessagePos();                  // Get mouse position

        winMsg.pt.x = LOWORD(msgPos);               // Extract x coordinate

        winMsg.pt.y = HIWORD(msgPos);               // Extract y coordinate

        

        NativeEventToMacEvent (&winMsg, &qtmlEvt);  // Convert to event

             

        MCIsPlayerEvent (theController, &qtmlEvt);  // Pass event to QuickTime

        

        switch ( msgType )                          // Dispatch on message type

            {   

                

                ·                                   // Handle message according to type

                ·

                

            }  /* end switch ( msgType ) */

        

    }  /* end WinProc */